home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / px141.zip / PX.DOC < prev    next >
Text File  |  1991-05-19  |  8KB  |  208 lines
  1.  
  2.                                   PX
  3.               Pascal Source Cross Referencer - Version 1.4
  4.             Copyright (c)1989,1991 by P.A. Geelen, Amsterdam
  5.  
  6.  
  7.            The program PX.EXE and this document are placed in the
  8.     public domain by the author. It may be used and distributed freely.
  9.                  It may not be sold under any condition, 
  10.                nor be made part of anything that is sold. 
  11.  
  12.  
  13.  
  14. PX is a program specialized in cross-referencing PASCAL programs.
  15. It will cross-reference:
  16.  
  17.    - procedures and functions, their declarations and usage
  18.    - procedure/function calls
  19.    - variable declarations and usage
  20.  
  21. The output is best shown by a small example.
  22. There are several options for the use of PX, but the most extensive
  23. output will be generated using
  24.  
  25.        PX /v
  26.  
  27. Suppose we have the following program, EXAMPLE.PAS
  28. (the line numbers are depicted for convenience only):
  29.  
  30.        1. var i,j:integer;
  31.        2.
  32.        3.   procedure SubProc;
  33.        4.   var x,y,z:integer;
  34.        5.       procedure EvenSmallerProc(i);
  35.        6.       var z:integer;
  36.        7.       begin x:=i+j+y+z; end;
  37.        8.   begin {SubProc}
  38.        9.     x:=i; EvenSmallerProc(x);
  39.       10.   end;  {SubProc}
  40.       11.
  41.       12. begin
  42.       13.   i:=5; j:=i;
  43.       14.   writeln(i,' ',j);
  44.       15.   repeat SubProc until keypressed;
  45.       16. end.
  46.  
  47. The output of "PX /V" would then be:
  48.  
  49.      C:\MY\UTIL\EXAMPLE.PAS
  50.      Procedure Cross Reference 1.4 - P.A.Geelen, Amsterdam, 1989,1991
  51.  
  52.      MAIN program [1-16]
  53.       vars : I [1].......................14,13,13,*9,
  54.              J [1].......................14,13,*7,
  55.             *KEYPRESSED <external>.......15,
  56.       uses : subproc.....................15,
  57.  
  58.      SUBPROC procedure [3-10]
  59.       vars :*I [main:1]..................9,
  60.              X [4].......................9,9,*7,
  61.              Y [4].......................*7,
  62.              Z [4].......................
  63.       parts: EVENSMALLERPROC,
  64.       used : main........................15,
  65.       uses : evensmallerproc\subproc.....9,
  66.  
  67.      EVENSMALLERPROC procedure [5-7]
  68.       in   : \subproc
  69.       vars : I [5].......................7,
  70.             *J [main:1]..................7,
  71.             *X [subproc:4]...............7,
  72.             *Y [subproc:4]...............7,
  73.              Z [6].......................7,
  74.       used : subproc.....................9,
  75.  
  76.  
  77.  
  78. The meaning is as follows:
  79.  
  80.      MAIN program [1-16]
  81.       VARS:  I [1].......................14,13,13,*9,
  82.              J [1].......................14,13,*7,
  83.             *KEYPRESSED <external>.......15,
  84.       uses:  subproc.....................15,
  85.  
  86. means that
  87. - your main program spans lines 1-16.
  88. - It uses the identifiers I,J, and KEYPRESSED.
  89. - I is declared at line #1, and used on lines 14, 13 (twice) and 9.
  90.   The star before 9 means that I is used there from WITHIN ANOTHER
  91.   FUNTION or procedure (procedure SubProc, to be specific).
  92. - J is declared at line 1, and used on lines 14, 13, and 7.
  93. - KEPRESSED is used on line 15. The star before KEYPRESSED means that
  94.   the identifier does not belong to MAIN itself. <external> means that
  95.   the identifier does, indeed, not belong to the PROGRAM.
  96.   (in this case, it belongs to TURBO PASCAL's CRT unit).
  97. - the procedure SUBPROC is called once, from line 15.
  98.  
  99.      SUBPROC procedure [3-10]
  100.       VARS: *I [main:1]..................9,
  101.              X [4].......................9,9,*7,
  102.              Y [4].......................*7,
  103.              Z [4].......................
  104.       parts: EVENSMALLERPROC,
  105.       used : main........................15,
  106.       uses : evensmallerproc\subproc.....9,
  107.  
  108. This states that
  109. - there is a procedure SUBPROC, spanning lines 3-10.
  110. - It is used (acalled) once, from the main program, on line 15.
  111. - It contains the declaration of a private procedure, EVENSMALLERPROC,
  112.   which it uses on line 9.
  113. - It uses the variable I at line 9, and as we can see, this variable is
  114.   NOT a local variable, but a variable that has been declared on line 1
  115.   of the MAIN program.
  116. - The variables X,Y and Z are declared on line 4. Z is never used.
  117.   Y is used once, on line 7, and the star shows that is is used from
  118.   within a sub-procedure. X is used twice on line 9, and (as part of a
  119.   subprocedure) once on line 7.
  120.  
  121.      EVENSMALLERPROC procedure [5-7]
  122.        \subproc
  123.       VARS:  I [5].......................7,
  124.             *J [main:1]..................7,
  125.             *X [subproc:4]...............7,
  126.             *Y [subproc:4]...............7,
  127.              Z [6].......................7,
  128.       used : subproc.....................9,
  129.  
  130. means that
  131. - the function EVENSMALLERPROC spans lines 5-7, and is part of the
  132.   procedure SUBPROC. It is used once, from line 9 of subproc.
  133. - It uses local variables I and Z, it uses external variables
  134.   X and Y (belonging to SUBPROC and both declared on line 4), and it
  135.   uses the external variable J which belongs to the main procedure
  136.   and has been declared on line 1.
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144. Now, for the usage:
  145.  
  146. USAGE:
  147.           PX [filespec] [dumpfile] [options]
  148.  
  149. where
  150.      [filespec] is a (wildcarded) file specification.
  151.                 It is optional, and if left out, "*.PAS" is assumed.
  152.                 In that case, PX provides a file selection window.
  153.      [dumpfile] Is the destination. If left out, the output is
  154.                 sent to the screen.
  155.      [options]  may be any combination of the following:
  156.                 /m  - crossreference only MAIN and the MAIN procedures:
  157.                       Sub-procedures are not cross-referenced. They
  158.                       are only mentioned as PARTS of the procedures
  159.                       in which they occur.
  160.                 /c  - do not crossreference USES/USED:
  161.                       only the procedures and their line-numbers
  162.                       are displayed.
  163.                 /u  - crossreference USES, not USED:
  164.                       just show the procedures, and which other
  165.                       procedures they call.
  166.                 /v  - also cross-reference variables.
  167.                 /n  - cross-reference variables, but only the
  168.                       non-local variables.
  169.                 /e  - do not crossreference externals when
  170.                       cross-referencing variables (such as KEYPRESSED).
  171.  
  172. So, suppose we would use
  173.  
  174.     PX EXAMPLE.PAS DUMP /nmec
  175.  
  176. we would get only
  177.  
  178.  
  179.      MAIN program [1-16]
  180.  
  181.      SUBPROC procedure [3-10]
  182.       VARS: *I [main:1]..................9,
  183.       parts: EVENSMALLERPROC,
  184.  
  185.  
  186. i.e. EVENSMALLERPROC is not cross-references (because of the M-option),
  187. KEYPRESSED is not mentioned (because of the E-option), procedures
  188. calls are not cross-referenced (because of the C-option),
  189. and non-local variables are mentioned (because of the N-option).
  190.  
  191.  
  192. Customizing PX
  193. ==============
  194. To the file PX.EXE belongs a file PX.DAT, in which the keywords of
  195. PASCAL are described. These keywords will be excluded from the
  196. cross-reference. Lines starting with a semi-colon ";" are ignored.
  197. You can add other keywords to be excluded. However, before you adapt
  198. this file to exclude too many keywords, remember that the /E-option
  199. will prevent output of all externals anyway.
  200.  
  201.  
  202.  
  203. HISTORY
  204.  
  205.   PX 1.0 - 20/05/89 : just showed procedures and their line-spans
  206.   PX 1.1 - 05/09/89 : added CALLS/CALLED cross reference
  207.   PX 1.2 - 29/10/89 : added variable cross reference
  208.   PX 1.4 - 19/05/91 : added file selection window and PX.DAT